home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
Tech Arsenal 1
/
Tech Arsenal (Arsenal Computer).ISO
/
tek-03
/
basdoc20.zip
/
BASDOC.TXT
< prev
next >
Wrap
Text File
|
1992-10-22
|
84KB
|
1,591 lines
BASIC Insight (tm)
Version 2.00
User's Manual
Shareware Version
(C) Copyright 1992 - All Rights Reserved
McKelvy Enterprises
3149 Bradford Place
Birmingham, AL 35242
CompuServe ID: 71477,3513
LICENSE
The BASIC Insight software and manual are copyrighted, all rights are
reserved. You have purchased a license to use this software on one
machine at a time. You are authorized to make copies of BASIC Insight for
the sole purpose of backing up your software and protecting your
investment from loss.
Note: This copy of BASIC Insight is being distributed as Shareware. This
means that you may copy the disk just as you received it and you may give
it to others for their trial use. You are also permitted and encouraged to
upload this version to electronic bulletin board services. You may not,
however, resell or collect any fee for the distribution of BASIC Insight
without the permission of McKelvy Enterprises. (This does not include the
normal fees for using bulletin boards.) If you continue to use BASIC
Insight after your trial use, you must pay the purchase price as detailed
below.
WARRANTY
This software will perform as described herein only if properly applied.
Our liability to you is limited to replacing the software (FOR REGISTERED
USERS ONLY). We have no liability to you for any damage or loss (whether
special, incidental, or consequential) caused by this software, either
directly or indirectly.
You agree to the terms of this license by your decision to use this
software.
SHAREWARE
BASIC Insight is copyrighted. It is not a public domain program. It is
being distributed as Shareware, which means that unmodified copies of the
software and documentation may be freely copied and shared. We ask in
return that should you find BASIC Insight to be a useful program, you
become a registered user by sending $30.00 to:
McKelvy Enterprises
3149 Bradford Place
Birmingham, AL 35242
The file ORDER.FRM on the disk can be printed and used as an order form.
By becoming a registered user, you get:
o The latest version of the software without the introductory
Shareware screen.
o Free telephone (your Quarter) support for help with problems in
running BASIC Insight. In addition, you may make suggestions on how
to improve the program. You may also get support by writing to us
at the above address (this is the preferred method).
o A bound user's manual showing sample code (some with intentional
errors) and the output produced by BASIC Insight.
o Information on new versions of BASIC Insight as soon as they are
available.
o The source code for BASIC Insight (available to registered users for
an additional fee).
The shareware philosophy is to pay smaller amounts for well-crafted and
useful software from developers who cannot spend the millions of dollars
on packaging and marketing necessary to compete with the large software
development companies. You benefit by being able to try (for free) a wider
variety of software products to find the ones that best suit your
particular purpose. The shareware developer benefits from being able to
distribute his work to a wider audience than would be possible through
normal channels. In order for Shareware to grow and prosper (with the
development of more and better products), it is your responsibility to
distribute your shareware programs to others and to become a registered
user of those products you like and use.
1.0 Introduction
BASIC Insight is a program designed to help with the documentation and debugging
of BASIC programs. The program is specifically designed for use with programs
developed with Microsoft's QuickBASIC (tm) or Professional Development System
(PDS) (tm). It may also be used to process programs written with Visual BASIC,
provided that the programs have been saved in text format. BASIC Insight has
been tested with programs written in IBM's BASICA and Microsoft's GW-BASIC and
worked equally well with these programs.
The purpose of BASIC Insight is to provide the system developer with a formatted
source listing and variable cross-reference for BASIC programs. The formatted
listing will show DO..LOOP and WHILE..WEND ranges, IF..THEN..ELSE..END IF true
and false ranges, and the range of each CASE statement in a SELECT CASE group.
The listing will also display error messages if program loops are improperly
nested. The variable cross-reference will show the name of each variable or
BASIC keyword in a subroutine (or the main module) and the line numbers where the
variable is referenced. Additionally, a global variable cross-reference is also
available. This shows the names of the subroutines which use each variable or
BASIC keyword. The program documentation along with its table of contents may
be written either to a file or to the printer.
In addition to the listing described above, BASIC Insight is also capable of
simultaneously producing an indented source listing. This is simply a copy of
the input program with all of the DO..LOOP, WHILE..WEND, IF..THEN..ELSE..END IF,
and SELECT CASE structures indented for easier reading. The indented source
listing is a program file and can be used like any other program file you might
create.
System Requirements
BASIC Insight will work on any IBM-compatible personal computer running MS-DOS
or PC-DOS 3.30 (or higher) with at least 512K of available memory. The program
may be run from a floppy drive, but a hard drive is recommended, and may be
essential, for the variable cross-reference due to the size of temporary files.
The program speed is, of course, dependent on processor speed, but does not seem
to be dependent on processor type (i.e., 286 vs 386). A program of about 2000
lines can be processed in less than a minute without the cross-reference, and in
about two minutes with the cross-reference running on a 20MHz 386 machine.
What's New
Version 2.00 is a major re-write of BASIC Insight. The features incorporated
into the new version are: 1) menu operation (similar to QuickBASIC menus, 2)
enhanced command line operation, 3) support for MAK files (lists of files to
process) and INCLUDE files, 4) the ability to save and recall certain program
configuration information (i.e., page layouts, page headers, etc.), 5) a user
definable page header, 6) both local and global variable concordances (cross-
references), 7) separation of variables and BASIC keywords, 8) indented source
output, 9) documentation table of contents, 10) support for Visual BASIC
programs, and 11) mouse support.
2.0 Running BASIC Insight
You can run BASIC Insight in either a menu mode or a command line mode. In
either case, you start the program by typing BASDOC, followed by any command line
options, at the DOS prompt and pressing <Enter>. This assumes either that you
are in the directory which contains BASIC Insight or that you have that directory
specified in your PATH statement. If this is not the case, you will need to
specify the full path to the BASIC Insight executable file (i.e.,
C:\BASDOC\BASDOC).
As stated, a number of the programs options can be specified from the command
line using command line options. Command line options are designated by a slash
(/), followed by a letter, followed by the option data. The command line option
of /G causes the program to bypass the menus, run the analysis of the specified
program, and return to the DOS prompt. If the /G option is not specified, then
any options entered will be used as the initial values in the menus.
In the following descriptions, each section will describe a menu option, and the
equivalent command line option (if any) will be specified. In addition, the
command line options will be summarized in Appendix A. The four main menu
options (File, Options, Run, and Help) are described in Sections 2.1 through 2.4
respectively. In each menu section, the text will be referred to input
structures such as an input box, list box, check box, and option box. These
input structures and how they are used will be described in Appendix B.
In either mode of operation, as BASIC Insight is running, information about the
program being analyzed and the format of the output will be displayed on the
screen in an information box as shown below:
+===========================================================================+
| |
| Input File: C:\BASIC\SAMPLE.BAS |
| Output to: C:\BASIC\SAMPLE.LST |
| MAK File?: No Process INCLUDE Files?: No |
| Create formatted source files?: Yes Extension: SRC |
| |
| Local Concordance: Variable: Yes Keyword:No |
| Global Concordance: Variable: Yes Keyword:No |
| |
| Line Length: 115 Lines per Page: 60 |
| Number of Characters to Indent: 3 |
| Page Header: |
| Date: \D File: \F Page: \P |
| Version of BASIC: QB 4.5 |
| |
| |
| |
+===========================================================================+
2.1 File Menu
The File Menu (Figure 2.1) allows the user to 1) specify the input file, 2)
identify the input file as a list of files to be processed, 3) specify the output
device, 4) indicate that indented source files are to be created, 5) read a
configuration file, 6) save a configuration file, or 7) exit the program. The
File Menu is accessed by pressing <Alt>-F (holding down the Alt key while
pressing F) or by placing the mouse cursor over the word file and clicking the
left button. Once the menu is displayed, a selection may be made by pressing the
highlighted letter, using the cursor keys to highlight the selection and pressing
<Enter>, or placing the mouse cursor over the selection and clicking the left
mouse button. In Figure 2.1, the highlighted letter for each selection is shown
in boldface type.
+========================= Figure 2.1 File Menu ======================+
| |
| File Options Run Help |
| +--------------------+ |
| | Input File | |
| | MAK File | |
| +--------------------+ |
| | Output | |
| | Indented Source | |
| +--------------------+ |
| | Read Configuration | |
| | Save Configuration | |
| +--------------------+ |
| | Exit | |
| +--------------------+ |
| |
+======================================================================+
2.1.1 Input File
When the Input File option is selected from the menu, the user is prompted with
an input box (shown in Figure 2.2) in which to enter a file specification. The
user may enter a complete file name (optionally including a file path), or may
enter a file name containing wildcard characters (i.e., asterisk - *, or question
mark - ?). If a complete file name is entered, the program checks for the file's
existence and notifies the user if the file is not found. If wildcards are used,
the user is presented with a list box containing file names (example in Figure
2.3) which match the file specification and the user may then choose a file from
the list. If the user selects <Cancel> from the list box, then a message is
displayed reminding the user that no file was selected.
If the user does not specify a path in the input file description, then the
default path for source files is used. This path is specified in the File Paths
menu option described in Section 2.2.3. Once the input file has been specified,
the name (along with the full path) is shown in the program information box.
Command Line Option: /Finput file
When specifying the input file from the command line, the input file must be
specified, must immediately follow the /F, and Wildcards may not be used. Also,
the path for the files is assumed to be the current directory if no path is
specified.
+============== Figure 2.2 File Specification Input Box =================+
| |
| +----------------------------------------------------------+ |
| | | |
| | Enter a file specification: | |
| | +-----------------------------------+ | |
| | | *.* | | |
| | +-----------------------------------+ | |
| | | |
| | < OK > | |
| | | |
| | | |
| +----------------------------------------------------------+ |
| |
+==========================================================================+
+================ Figure 2.3 File List Box ==========================+
| +---------------------------+ |
| | +----------------+ | |
| | | SAMPLE1.BAS | | |
| | | SAMPLE1.EXE ^ | |
| | | SAMPLE1.LST * | |
| | | SAMPLE1.OBJ # | |
| | | SAMPLE2.BAS # | |
| | | SAMPLE2.EXE # | |
| | | SAMPLE2.LST # | |
| | | SAMPLE2.OBJ # | |
| | | SAMPLE3.BAS # | |
| | | SAMPLE3.EXE # | |
| | | SAMPLE3.LST # | |
| | | SAMPLE3.OBJ v | |
| | | TEST.BAT | | |
| | +----------------+ | |
| | | |
| | < OK > < Cancel > | |
| | | |
| +---------------------------+ |
| |
+=======================================================================+
2.1.2 MAK File
This option specifies whether or not the file entered as the input file is in
fact a list of files to be processed. The list of files must be in ASCII format
with one file per line. On each line, the file name must be the first entry on
the line and must be separated from any other information on the line by a space.
The status of the option is displayed in the information box, and is shown on the
menu by the presence (if activated) or absence (not activated) of a » mark.
Command Line Option: /M
2.1.3 Output
When the Output option is selected from the menu, an option box (Figure 2.4) is
presented which allows the user to select None (for no documentation output),
File (for output to a file), or Printer (for output to a print device).
If None is selected, no documentation output is produced. This option
would be selected if the user only wants to produce an indented source
file as described in Section 2.1.4.
If File is selected, the user is prompted with an input box in which to
enter a file specification. The user may enter a complete file name
(optionally including a file path), or may enter a file name containing
wildcard characters. If a complete file name is entered, the program
checks for the file's existence and notifies the user if the file is
found, asking if it should be overwritten. If wildcards are used, the
user is presented with a list of files which match the file specification
and the user may then choose a file from the list. If the user does not
specify a path in the output file description, the default path for source
files is used. This path is specified in the File Paths menu option
described in Section 2.2.3. The input box and list box for the output
file are the same as those for the input files (Figures 2.2 and 2.3).
If Printer is selected, the user is presented with a list box (Figure 2.5)
containing the print devices LPT1 - LPT4 and COM1 - COM4, and a selection
of the print device is made from the list. Once the output device has
been specified, the information is displayed in the information box.
Command Line Option: /Ooutput
When specifying the output device from the command line, the user should either
enter a complete file name (including the file path if necessary) or the name of
a print device (i.e., LPT1 or COM1). As with the input file, wildcards may not
be entered from the command line. If no output device is specified on the
command line, then "None" is assumed.
+====================== Figure 2.4 Output =============================+
| |
| +=================== Output Device Selection ==================+ |
| | | |
| | | |
| | | |
| | Output Devices for Documentation File | |
| | (*) None ( ) File ( ) Printer | |
| | Output to: | |
| | | |
| | | |
| | < Cancel > | |
| | | |
| +==============================================================+ |
| |
+========================================================================+
+================ Figure 2.5 Printer List Box =======================+
| +---------------------------+ |
| | +----------------+ | |
| | | LPT1 | | |
| | | LPT2 ^ | |
| | | LPT3 * | |
| | | LPT4 # | |
| | | COM1 # | |
| | | COM2 # | |
| | | COM3 v | |
| | | COM4 | | |
| | +----------------+ | |
| | | |
| | < OK > < Cancel > | |
| | | |
| +---------------------------+ |
| |
+=======================================================================+
2.1.4 Indented Source Listing
This option allows the user to generate indented source files. These files are
the same as the input program files except that command structures (such as DO
loop, IF statements, CASE structures, etc.) are indented by a specified number
of spaces. This makes the source code itself easier to read, but does not affect
the performance of the program. It can still be edited and compiled like any
other program file. When the option is selected, an option box is presented
asking if source files are to be created. The user selects either the "Yes" or
"No" button in the box. The extension for the source file is specified in the
File Paths menu option described in Section 2.2.3. The default file extension
is "SRC".
Command Line Option: /Sext
When specifying from the command line that source files are to be created, the
file extension for the files must be specified.
2.1.5 Read Configuration File
When this option is selected, information about the analysis to be performed and
the layout of the documentation is read in from a file. The information includes
whether local and/or global concordances (for variables or keywords) should be
generated, the number of spaces to indent structures, the length of the output
line, the number of lines per page, the page header, and the default language to
use for keyword lookup. The configuration file used in the menu options is
always BASDOC.CFG and is found in the path designated in the File Paths menu
option (Section 2.2.3).
Command Line Option: /Cfilename
When specifying the configuration file from the command line, the configuration
file may have any file name. It is recommended that the configuration file be
placed prior to other format options on the command line, as the information in
the file will override any format information already entered.
A sample configuration file and a description of how to create a file can be
found in Appendix C.
2.1.6 Save Configuration File
When this option is selected, information about the analysis to be performed and
the layout of the documentation is saved to a file. The information includes
whether local and/or global concordances should be generated, the number of
spaces to indent structure, the length of the output line, the number of lines
per page, the page header, and the default language to use for keyword lookup.
The configuration file name used is always BASDOC.CFG, and the file is output to
the path designated in the File Paths menu option (Section 2.2.3).
2.1.7 Exit
Choosing this option terminates the program and returns the user to the DOS
prompt.
2.2 Options Menu
The Options Menu (Figure 2.6) allows the user to specify the output page format,
the analysis options, and the file paths for various files used by BASIC Insight.
The Options Menu is accessed by pressing <Alt>-O (holding down the Alt key while
pressing O) or by placing the mouse cursor over the word Options and clicking the
left button. Once the menu is displayed, a selection may be made by pressing the
highlighted letter, using the cursor keys to highlight the selection and pressing
<Enter>, or placing the mouse cursor over the selection and clicking the left
mouse button. In Figure 2.6, the highlighted letter for each selection is shown
in boldface type.
+======================= Figure 2.6 Options Menu =====================+
| |
| File Options Run Help |
| +--------------------+ |
| | Page Layout | |
| | Processing Options | |
| | File Paths | |
| +--------------------+ |
| |
+======================================================================+
2.2.1 Page Layout
The Page Layout option allows the user to enter format information such as the
number of spaces to indent structures, the number of characters per line, the
number of lines per page, and the header to be printed at the top of each page.
When the Page Layout option is selected, the user is presented with the input box
shown in Figure 2.7. The shaded regions indicate edit fields where the user
actually enters the information. After filling out the information, the user may
select <Accept> to use the entered data, or <Cancel> to return the format
settings to their previous values.
+================= Figure 2.7 Page Layout Screen =======================+
| |
| +=================== Page Layout Options ==========================+ |
| | | |
| | Number of Spaces to Indent: 4 | |
| | | |
| | Number of Characters Per Line: 132 | |
| | | |
| | Number of Lines Per Page: 55 | |
| | | |
| | Page Header String: | |
| | Date: \D Time: \T Filename: \N Subroutine: \S Page | |
| | | |
| | < Accept > < Cancel > | |
| | | |
| +==================================================================+ |
+=========================================================================+
2.2.1.1 Spaces to Indent
This option specifies the number of spaces to indent each "nest" of DO loops,
FOR..NEXT loops, etc. This value controls the appearance of the formatted
output. Each statement within the range of a loop is shown with a loop
descriptive character and the number of spaces requested by the user in front of
it (as shown in the example below). For indented source output files the effect
is similar, but there are no line numbers or loop descriptive characters present.
Program Segment:
DO WHILE condition
statement 1
statement 2
statement 3
LOOP
Formatted Listing (with 4 spaces selected):
1 DO WHILE condition
2 L statement 1
3 L statement 2
4 L statement 3
5 LOOP
In this example, the numbers to the far left are line numbers, and the "L" is the
DO loop descriptive character.
Indented Source File (with 4 spaces selected):
DO WHILE condition
statement 1
statement 2
statement 3
LOOP
The user can request any number of spaces (up to 10) for the indent function, but
recommended values are from 1 to 5.
Command Line Option: /Nx
When entered from the command line, the user enters the number of space to indent
(i.e., /N4).
2.2.1.2 Characters Per Line
This option specifies how many characters will be printed before BASIC Insight
breaks the program statement into two or more output lines. The length specified
will be the number of characters on a line, including the line number, any
indentations (see Section 2.2.1.1), and the program statement. The user may
input a value of 0, which will tell the program not to split the lines, or any
integer value greater than 50. The actual line length to be used will depend on
the paper width and print font to be used to print the output file. A value of
132 and a compressed font (17 cpi) for printing works well for most programs.
For indented source output, lines are never split and this value is ignored.
Command Line Option: /Lxxx
When entered from the command line, the user enters the number of characters per
line (i.e., /L132).
2.2.1.3 Lines Per Page
This option specifies the number of lines to be printed per page when the file
is sent to a printer. The program will issue a form feed character each time the
"lines per page" counter exceeds the input value. The program will also issue
a form feed each time a new subroutine or function is encountered. The lines
printed on a page also includes the three-line report header which is printed at
the top of each page. While most printers can print up to sixty-six lines per
page (some can print more), a value of 55 lines per page seems to work well for
most printer setups.
Command Line Option: /Pxx
From the command line, the user enters the number of lines per page (i.e., /P55).
2.2.1.4 Page Header
This option specifies the page header (single line) to be printed at the top of
each page of the output report. The page header can be as long as the line
length specified in Section 2.2.1.2, and can contain any descriptive text the
user wants to include. In addition, the user may include backslash (\) operators
in the text to have program-dependent data printed in the header. These
operators take the form of \A, where "A" is one of the following five
descriptors:
D - The date that the report was run. This is pulled from the system
date function.
T - The time that the run started. This is pulled from the system time
function.
N - The name of the file being processed. This can be useful when
processing a MAK file, as the program will use the names of the
files being analyzed to show which routines are part of which file.
S - The current subroutine being processed. This is taken from the SUB
or FUNCTION statement at the beginning of each routine. For the
first routine (which is unnamed), the default name of "Main" is used
for all programs except Visual BASIC programs where the default name
is "Declarations".
P - The current page number.
When entering this data in the edit field, up to 132 characters will be accepted
as input, but only 60 characters will be displayed at a time.
Command Line Option: /Hpage_header_information
When entering the page header data from the command line, an underscore (_) must
be used to indicate each space in the header string. This is required since the
module which processes the command line options looks for spaces to separate the
different options. Each underscore will be converted to a space prior to
printing the page header.
2.2.2 Processing Options
The Processing Options choice allows the user to make choices about the type of
concordances (local or global cross-references of variables and/or keywords) to
have printed, the language used by the program being analyzed (this is to
determine the keyword set to be used), and whether or not to process INCLUDE
files. The user is presented with an input panel (Figure 2.8) which contains a
series of check boxes, a set of radio buttons for choosing the language, and
command buttons for processing the input. After making selections of processing
options, the user may select <Accept> to use the selected choices, or <Cancel>
to return the processing options to their previous settings.
+================= Figure 2.8 Processing Options Screen ===============+
| |
| +===================== File Processing Options =====================+ |
| | | |
| | Local Concordances: Global Concordances: | |
| | [X] Variables [X] Variables | |
| | [ ] Keywords [ ] Keywords | |
| | | |
| | [ ] Process INCLUDE Files | |
| | | |
| | Language to use for Keywords | |
| | (*) None ( ) PDS 7.1 ( ) QB 4.5 ( ) VB | |
| | | |
| | < Accept > < Cancel > | |
| | | |
| +===================================================================+ |
+=========================================================================+
2.2.2.1 Variable Concordances
A variable concordance is a listing of the variables used in a subroutine or a
program along with information about where they are used. A local variable
concordance may be printed at the end of each subroutine, and lists the variables
used in that subroutine and the line numbers on which they appear. This is often
useful in discovering typographical errors, or in determining where the value of
a variable has been redefined. To select local variable concordance from the
input panel, mark the Variables check box under Local Concordances. A global
variable concordance may be printed at the end of the program, and lists all the
variables used in the program and the subroutines in which they appear. This is
useful in helping to determine what effect (if any) changing the value of a
variable in one subroutine will have on another subroutine. To select global
variable concordance from the input panel, mark the Variables check box under
Global Concordances.
Command Line Option: /Va
From the command line, the letter following the /V determines the type of
variable concordance to be printed. For a local concordance, enter L; for a
global concordance, enter G; or to have both local and global concordances
printed, enter B.
2.2.2.2 Keyword Concordances
A keyword concordance is a listing of the keywords used in a subroutine or a
program along with information about where they are used. A keyword concordance
is most useful in determining the effect of a version change of a language when
the operation or syntax of a command might have changed. It is also very useful
when porting code from one flavor of BASIC to another (i.e., QuickBASIC to Visual
BASIC), or to another language, to determine what commands or functions are
required by a program that might not be present in the new language. A local
keyword concordance may be printed at the end of each subroutine, and lists the
keywords used in that subroutine and the line numbers on which they appear. To
select local keyword concordance from the input panel, mark the Keywords check
box under Local Concordances. A global keyword concordance may be printed at the
end of the program, and lists all the keywords used in the program and the
subroutines in which they appear. To select global keyword concordance from the
input panel, mark the Keywords check box under Global Concordances.
Command Line Option: /Ka
From the command line, the letter following the /K determines the type of keyword
concordance to be printed. For a local concordance, enter L; for a global
concordance, enter G; or to have both local and global concordances printed,
enter B.
2.2.2.3 INCLUDE Files
INCLUDE files are small segments of BASIC code which provide subroutine
declarations, definitions of constants, TYPE declarations, COMMON blocks, and
array or variable dimensions. These files are most often used in conjunction
with libraries such as interface, graphics, or financial functions, but may also
be used if you have certain code pieces that you use in several of your programs.
When this option is invoked, BASIC Insight will process INCLUDE files as it
encounters them, provided that the file is found. When INCLUDE files are
processed, their statements are preceded by "## " prior to any other indent
characters. This helps set them off from the rest of your code. To select
INCLUDE file processing from the input box, mark the check box for "Process
INCLUDE Files".
Command Line Option: /I
When selecting INCLUDE file processing from the command line, enter the /I
option. There are no additional characters required.
2.2.2.4 Programming Language
The purpose of selecting the programming language used is to determine the
keyword set to be used in the processing of the variable and keyword
concordances. If no language is selected, BASIC Insight treats both variables
and keywords the same, and processes them as variables in the concordances. Also
no keyword concordance is possible. The other reason for specifying the language
is that the untitled routine at the beginning of a PDS 7.1 or QB 4.5 program file
is considered the "Main" routine. For Visual BASIC, this is considered the
declarations area. BASIC Insight uses the language specification to assign the
appropriate title to the first routine. To select the language from the input
box, mark the space in front of the appropriate language.
Command Line Option: /Bn
To select the programming language from the command line, the number following
the /B option is defined as follows: 1 for PDS 7.1, 2 for QB 4.5, and 3 for
Visual BASIC.
NOTE: If you are using BASIC Insight with a language other than one of the three
that are specifically supported, a custom version of the code tailored for that
language can be provided for you (for a small fee) if you will provide us with
the keyword list.
2.2.3 File Path Specification
The File Path option allows the user to enter path information for files used by
BASIC Insight. These are the configuration files, keyword files, help files, and
source program files. The default value for the path for configuration, keyword,
and help files is the subdirectory where the BASIC Insight executable file is
located. The default for the source program files is the current directory. The
user may also enter the file extension to be used for indented source output
files. The default extension is SRC. When the File Path option is selected, the
user is presented with the input box shown in Figure 2.9. The shaded regions
indicate edit fields where the user actually enters the information. After
filling out the information, the user may select <Accept> to use the entered
data, or <Cancel> to return the path settings to their previous values.
+=================== Figure 2.9 File Path Input Screen ==================+
| |
| +========================== Path Definitions ==========================+ |
| | | |
| | Path for Configuration File: | |
| | C:\BASDOC\ | |
| | | |
| | Path for Keyword Files: | |
| | C:\BASDOC\ | |
| | | |
| | Path for Help Files: | |
| | C:\BASDOC\ | |
| | | |
| | Path for Source Code Files: | |
| | C:\SAMPLES\ | |
| | | |
| | Extension for Output Source Files: | |
| | SRC | |
| | | |
| | < Accept > < Cancel > | |
| | | |
| +======================================================================+ |
+===========================================================================+
2.3 Run Menu
The Run Menu (Figure 2.10) allows the user to start the processing of the BASIC
programs to be analyzed, using the currently defined options. The Run Menu is
accessed by pressing <Alt>-R (holding down the Alt key while pressing R) or by
placing the mouse cursor over the word Run and clicking the left button. You
begin processing the file by pressing the highlighted letter (P), simply pressing
<Enter>, or placing the mouse cursor over the selection and clicking the left
mouse button.
+========================= Figure 2.10 Run Menu =======================+
| |
| File Options Run Help |
| +-----------------+ |
| | Process File(s) | |
| +-----------------+ |
| |
| |
| |
+======================================================================+
2.3.1 Process File(s)
Selecting this menu item starts the processing of BASIC programs. To show the
progress of the analysis, the program keeps a running count of the line number
being processed as shown in Figure 2.11. At the end of each routine, the program
will perform (if requested) the local variable and keyword concordance. While
this is being done, the program displays the variables being processed as shown
in Figure 2.12. A similar process occurs at the end of the program if a global
variable/keyword concordance has been requested. After the analysis is
completed, an alert box is displayed (Figure 2.13) that informs the user of the
completion of the run. Pressing <Enter> or clicking the <OK> button will return
the user to the menu.
Command Line Option: /G
When the command option /G is input on the command line, the menu is bypassed,
and processing begins immediately using the files and options specified on the
command line. When processing is completed, the program returns to the DOS
prompt. The main use of this option is to allow the building of a batch file to
process several different programs at once.
+================= Figure 2.11 Line Count Display =====================+
| |
| +----------------------------------------------+ |
| | | |
| | Processing line number: 50 | |
| | | |
| | | |
| | | |
| | | |
| | | |
| +----------------------------------------------+ |
| |
+=========================================================================+
+============ Figure 2.12 Variable Processing Display =================+
| |
| +----------------------------------------------+ |
| | | |
| | Processing line number: 183 | |
| | | |
| | | |
| | | |
| | | |
| +---------+----------------------------------------------+--------+ |
| | Printing Variable Cross-Reference | |
| | for Subroutine: Main | |
| | | |
| | lpix | |
| | | |
| | | |
| +-----------------------------------------------------------------+ |
| |
+=========================================================================+
+=============== Figure 2.13 Analysis Completion Screen ================+
| |
| |
| +---------------------------------------------+ |
| | Processing Completed | |
| | | |
| | | |
| | | |
| +---------------------------------------------+ |
| | < OK > | |
| +---------------------------------------------+ |
| |
| |
+=========================================================================+
2.4 Help Menu
The Help Menu (Figure 2.14) allows the user to access on-line help about the
settings of BASIC Insight and about the function of the program. The Help Menu
is accessed by pressing <Alt>-H (holding down the Alt key while pressing H) or
by placing the mouse cursor over the word Help and clicking the left button.
Once the menu is displayed, a selection may be made by pressing the highlighted
letter, using the cursor keys to highlight the selection and pressing <Enter>,
or placing the mouse cursor over the selection and clicking the left mouse
button. In Figure 2.14, the highlighted letter for each selection is shown in
boldface type.
+======================== Figure 2.14 Help Menu =======================+
| |
| File Options Run Help |
| +--------------------+ |
| | Index | |
| | About This Program | |
| +--------------------+ |
| |
| |
+======================================================================+
2.4.1 Index
When the Index option is selected, a list box showing the help topics (Figure
2.15) is displayed. The user may then select a help topic by highlighting the
topic and selecting the <OK> button, or return to the menu by selecting the
<Cancel> button. When a topic is selected, information about the topic is
displayed in a window as shown in Figure 2.16. Selecting the <OK> button from
the help topic screen returns the user to the help index.
+================ Figure 2.15 Help Index Box =========================+
| +---------------------------+ |
| | +-----------------+ | |
| | | About Box | | |
| | | Characters Per ^ | |
| | | File Menu * | |
| | | File Path Def # | |
| | | Help Index # | |
| | | Help Menu # | |
| | | INCLUDE Files # | |
| | | Indented Source # | |
| | | Input File # | |
| | | Keyword Concord # | |
| | | Lines Per Page v | |
| | | MAK File | | |
| | +-----------------+ | |
| | | |
| | < OK > < Cancel > | |
| | | |
| +---------------------------+ |
| |
+=======================================================================+
+================== Figure 2.16 Help Window ==============================+
| |
| +------------------------------------------------------------------------+ |
| | Characters Per Line: | |
| | This option specifies how many characters will be printed before the | |
| | BASIC Insight breaks the program statement into two or more output | |
| | lines. The length specified will be the number of characters on a | |
| | line, including the line number, any indentations (see Spaces to | |
| | Indent), and the program statement. The user may input a value of 0, | |
| | which will tell the program not to split the lines, or any integer | |
| | value greater than 50. The actual line length to be used will depend | |
| | on the paper width and print font to be used to print the output file. | |
| | For my own work, I use a value of 132 and a compressed (17 cpi) font | |
| | for printing. For indented source output, lines are never split and | |
| | this value is ignored. | |
| | | |
| | | |
| | | |
| +------------------------------------------------------------------------+ |
| | < OK > | |
| +------------------------------------------------------------------------+ |
| |
+============================================================================+
2.4.2 About This Program
This option displays a window (like the help window in Figure 2.16) that contains
a general description of the program. Selecting the <OK> button returns the user
to the main menu.
2.4.3 Command Line Help
Command Line Option: /?
When this option is entered on the command line, the program prints out to the
screen a listing of the command line options, including a brief description of
each.
3.0 Enhancements
Future versions of BASIC Insight may be developed and released to enhance the
capabilities of the current program. Below is a list of possible program
enhancements for later versions. Input from registered users will help determine
the priority in which these get implemented. Additional suggestions from users
may also be included. Enhanced versions of the program will be available to all
registered users for about $10. This covers the cost of postage and of new disks
and manuals.
Possible enhancements:
o Output directed to screen.
o Tree structure showing subroutine calls.
Appendix A: Command Line Options Summary
In the following text, the optional parameters that may be entered on the command
line will be described. Each option is preceded by a slash (/), is identified
by a single letter option designator (shown in boldface type), and is immediately
followed by the required input (shown in italics). In addition to the
description of the command, the default values for each option will be listed.
/Finput_file This option specifies the BASIC program source file to be
processed. The user must enter the complete filename of the
program source or MAK file. The user may optionally enter the
file path for the file, but if the path is omitted, the
current directory will be assumed. Wildcard characters (* or
?) are not permitted in the input file name. Default: None.
/M This option indicates that the file specified by the input
file option is actually a list of files to be processed. For
each file in the list, the path must either be specified in
the MAK file, or the file must reside in the current
directory. Default: None.
/Ooutput This option specifies the output file or device to be used for
the documentation output. If a file is to be used, the user
must specify a complete file name (wildcards are not allowed),
optionally including the file path. If the path is not
specified, the current directory is assumed. If a print
device is to be used, the user must specify the device name
(i.e., LPT1, LPT2, COM1, etc.). Default: No output.
/Cconfig_file This option specifies the name of a configuration file to be
read. This file (defined in Appendix C) contains page format
and file processing options to be used in running BASIC
Insight. Keeping these values in a configuration file
relieves the user from entering the information for each file
to be processed. The user must enter the complete name of the
file (no wildcards), and if the path is not specified, the
directory containing the file is assumed to be the same one
which contains the BASIC Insight executable file (BASDOC.EXE).
Default: None.
/I This option specifies that INCLUDE files should also be
processed. Default: None.
/N# This option specifies the number of spaces (up to 10) to
indent command structures. Default: 3.
/L### This option specifies the number of characters to print on
each line. BASIC Insight will break command lines at the end
of the number of characters specified in order to make the
output fit properly on the page. If a value of 0 is entered,
then lines are not broken. For indented source output files,
command lines are never broken and this option is ignored.
Default: 80.
/P## This option specifies the number of lines to be printed on
each page of the documentation output. Default: 60.
/Hpage_header This option specifies the page header (single line) to be
printed at the top of each page of the output report. The
page header can be as long as the line length specified above,
and can contain any descriptive text the user wants to
include. In addition, the user may include backslash (\)
operators in the text to have program-dependent data printed
in the header. These operators take the form of \A, where "A"
is one of the following five descriptors:
D - The date that the report was run. This is pulled from
the system date function.
T - The time that the run started. This is pulled from the
system time function.
N - The name of the file being processed. This can be
useful when processing a MAK file, as the program will
use the names of the files being analyzed to show which
routines are part of which file.
S - The current subroutine being processed. This is taken
from the SUB or FUNCTION statement at the beginning of
each routine. For the first routine (which is unnamed),
the default name of "Main" is used for all programs
except Visual BASIC programs where the default name is
"Declarations".
P - The current page number.
When entering the page header data from the command line, an
underscore (_) must be used to indicate each space in the
header string. This is required since the module which
processes the command line options looks for spaces to
separate the different options. Each underscore will be
converted to a space prior to printing the page header.
Default: None.
/Va This option specifies the type of variable concordance(s) to
be printed. The values of a are as follows: L for local
concordance, G for global concordance, or B for both
concordances. Default: None.
/Ka This option specifies the type of keyword concordance(s) to be
printed. The values of a are as follows: L for local
concordance, G for global concordance, or B for both
concordances. Default: None.
/B# This option specifies the programming language used in the
source file. This information is used to access a database of
keywords so that BASIC Insight can distinguish between
variables and keywords when generating the concordances. The
values of # for supported versions of BASIC are: 1 for
Professional BASIC (PDS), 2 for QuickBASIC, or 3 for Visual
BASIC. Any other value entered is ignored, and no language is
assumed. Default: 0 (no language).
/Sext This option specifies that BASIC Insight should create
indented source files using ext as the output file extension.
Default: SRC.
/G This options tells BASIC Insight to run the analysis using the
information specified on the command line (without accessing
the menu), and return to DOS upon completion. Default: No
additional parameters.
Appendix B: Use of Data Input Forms
BASIC Insight makes use of several user interface methods to make it easier to
move around the program and enter necessary data. These methods are pull-down
menus, input boxes, edit fields, check boxes, list boxes, radio button option
choices, and command buttons. In this section, techniques for using these
methods with either the keyboard or the mouse will be presented.
Pull-down Menus
BASIC Insight uses a pull-down menu for the main menu of the program. The menu
appears as a bar across the top of the screen, and as the main menu options are
selected, the sub-menu drops down below the menu bar. To access the main menu
options, the user may press the <Alt> key followed by one of the highlighted
letters on the menu bar (for example, Alt-F for the File Menu). Once the main
menu has been activated, the user may move between main menu options using the
left and right cursor keys. To select a sub-menu option using the keyboard, the
user may either press the highlighted letter of the menu option, or use the up
and down cursor keys to move the light bar to the option then pressing <Enter>.
To select a main menu choice using the mouse, the user places the mouse cursor
over the option name and clicks the left mouse button. To select a sub-menu
option, the user again moves the mouse cursor over the option and clicks the left
mouse button. Figure B.1 shows an example of the pull-down menus.
+======================= Figure B.1 Pull-Down Menu ===================+
| |
| File Options Run Help |
| +--------------------+ |
| | Input File | |
| | MAK File | |
| +--------------------+ |
| | Output | |
| | Indented Source | |
| +--------------------+ |
| | Read Configuration | |
| | Save Configuration | |
| +--------------------+ |
| | Exit | |
| +--------------------+ |
| |
+======================================================================+
Input Boxes
An input box is used to get a single piece of information from the user. Once
it has been activated by the program, the user enters the required data in the
input area, then presses <Enter> or clicks the mouse on the <OK> command button
to accept the entered information and continue the program. Figure B.2 shows an
example of an input box.
+====================== Figure B.2 Input Box ===========================+
| |
| +----------------------------------------------------------+ |
| | | |
| | Enter a file specification: | |
| | +-----------------------------------+ | |
| | | *.* | | |
| | +-----------------------------------+ | |
| | | |
| | < OK > | |
| | | |
| | | |
| +----------------------------------------------------------+ |
| |
+==========================================================================+
Edit Fields
Edit fields are used in groups on an input screen to obtain multiple pieces of
information from the user, usually about a related subject (i.e., page format
options). Each edit field is preceded by a data description and has a
highlighted area for actual data input. The user may move between edit fields
using the <Tab> and <Shift><Tab> keys, or by clicking on the field with the
mouse. In each edit field, the user enters the required information using the
keyboard. In BASIC Insight, the screens which use edit fields will also have an
<Accept> and a <Cancel> command button. These buttons are described below, and
are used to determine whether variables in the program are set to the newly
entered values (Accept), or reset to their previous values (Cancel). Using
either of these buttons will terminate the particular input screen. Figure B.3
shows an example of a screen with several edit fields.
+================= Figure B.3 Edit Field Example =======================+
| |
| +=================== Page Layout Options ==========================+ |
| | | |
| | Number of Spaces to Indent: 4 | |
| | | |
| | Number of Characters Per Line: 132 | |
| | | |
| | Number of Lines Per Page: 55 | |
| | | |
| | Page Header String: | |
| | Date: \D Time: \T Filename: \N Subroutine: \S Page | |
| | | |
| | < Accept > < Cancel > | |
| | | |
| +==================================================================+ |
+=========================================================================+
Check Boxes
Check boxes are used on an input screen to indicate options that are either on
or off. Each check box consists of a pair of square brackets, [], and a
description of the option. If the option is on, an "X" appears in the box
between the brackets. To toggle a check box using the keyboard, the user moves
the cursor to the check box using the <Tab> or <Shift><Tab> keys, then presses
the <Space> bar to toggle the option. Using the mouse, the user toggles the
check box value by clicking the left mouse key with the mouse cursor placed over
the check box. Like edit field input screens, command buttons will be used on
the screen with check boxes to process the options. Figure B.4 shows examples
of check boxes and radio buttons (described below).
+============= Figure B.4 Check Box and Radio Button Example ===========+
| |
| +===================== File Processing Options =====================+ |
| | | |
| | Local Concordances: Global Concordances: | |
| | [X] Variables [X] Variables | |
| | [ ] Keywords [ ] Keywords | |
| | | |
| | [ ] Process INCLUDE Files | |
| | | |
| | Language to use for Keywords | |
| | (*) None ( ) PDS 7.1 ( ) QB 4.5 ( ) VB | |
| | | |
| | < Accept > < Cancel > | |
| | | |
| +===================================================================+ |
+=========================================================================+
List Boxes
A list box is used to allow the user to make a selection among a series of
choices, such as a file list. To make a selection using the keyboard, the user
moves the cursor to the list area using the <Tab> keys, then uses the up and down
cursor and <Page Up> and <Page Down> keys to highlight the selection. The user
may then press <Enter> to accept the selection. Using the mouse, the user may
click on the selection in the list to highlight it, or may click on the scroll
bar (the shaded area to the right of the choices) to move through the list.
Clicking on one of the arrows on the scroll bar moves the highlight bar one
selection at a time, while clicking on the shaded area above or below the solid
block moves the highlight bar one page of selections at a time. Once the
selection is highlighted, the user clicks on the <OK> button to accept the
selection, or on the <Cancel> button to exit the list box without making a
selection. Figure B.5 shows an example of a list box.
+================ Figure B.5 List Box Example ========================+
| +---------------------------+ |
| | +-----------------+ | |
| | | About Box | | |
| | | Characters Per ^ | |
| | | File Menu * | |
| | | File Path Def # | |
| | | Help Index # | |
| | | Help Menu # | |
| | | INCLUDE Files # | |
| | | Indented Source # | |
| | | Input File # | |
| | | Keyword Concord # | |
| | | Lines Per Page v | |
| | | MAK File | | |
| | +-----------------+ | |
| | | |
| | < OK > < Cancel > | |
| | | |
| +---------------------------+ |
| |
+=======================================================================+
Radio Buttons
Radio buttons are used to allow the user to choose one of several available
choices. Radio buttons consist of a pair of parentheses along with a description
of the choice. The currently selected option has a diamond in the parentheses.
To select a radio button using the keyboard, the user moves the cursor to the
radio button using the <Tab> or <Shift><Tab> keys, then presses the <Space> bar
to select the option. Using the mouse, the user selects the radio button by
clicking the left mouse key with the mouse cursor placed over the radio button.
Figure B.4 shows examples of check boxes and radio buttons.
Command Buttons
Command buttons are used to initiate an action in the program. When used on an
input screen, they are most often used to either accept or cancel the input data
entered by the user. Command buttons consist of a command word enclosed in angle
brackets, <>. To select a command button with the keyboard, the user must use
the <Tab> keys to move the cursor to the command button. The user then presses
<Enter> to execute the command. With the mouse, the user just moves the mouse
cursor to the command button and clicks the left mouse button. <Accept> and
<Cancel> command buttons are shown in Figures B.3 and B.4.
Appendix C: Configuration File
A configuration file is a text file which contains the values of several program
configuration options. The file can be created with any editor which produces
ASCII text files. The keywords of the file and the values of the parameters are
read in as text strings and must be enclosed in double quotes ("). Each keyword
and value combination occupies one line of the file. The keywords and their
possible values are listed below. An example of a configuration file is shown
in Figure C.1.
Keyword Description and Value
LOCVAR Local variable concordance desired. Value - 1.
GBLVAR Global variable concordance desired. Value - 1.
LOCKEY Local keyword concordance desired. Value - 1.
GBLKEY Global keyword concordance desired. Value - 1.
DEFLNG Default language to use. Value - 1, 2, or 3 as
described in Section 2.2.2.4.
INDENT The number of spaces to indent structures. Value - 1
through 10.
LINLEN The number of character to print per line. Value - 0,
or any positive integer over 50.
PAGLNG The number of lines to print per page. Value - any
positive integer over 10.
HEADER The one-line header to be printed at the top of each
page. Value - header string as defined in Section
2.2.1.4.
+=============== Figure C.1 Sample Configuration File =======================================+
| |
| "LOCVAR" "1" |
| "GBLVAR" "1" |
| "DEFLNG" " 1" |
| "INDENT" " 4" |
| "LINLEN" " 132" |
| "PAGLNG" " 55" |
| "HEADER" "Date: \D Time: \T Filename: \N Subroutine: \S Page No: \P" |
+==============================================================================================+
Appendix D: Sample Program File
DECLARE SUB EndProg ()
INPUT #1, I
' Select case example
SELECT CASE I
CASE 1
PRINT "I="; I
CASE 2
PRINT "I="; -I
CASE 3
PRINT "I="; 0
END SELECT
'If example
IF I > 2 THEN
PRINT "Yes"
ELSE
PRINT "No"
END IF
'Do loop example
J = 1
DO UNTIL J = 5
PRINT J
J = J + 1
LOOP
'For example
FOR J = 1 TO 10
PRINT -J
NEXT J
CALL EndProg
END
SUB EndProg
J = 5 * 5
I = 5 ^ .33
PRINT "Five Squared is: "; J
PRINT "Cube root of twenty-five is: "; I
PRINT "End of Program"
END SUB
Appendix E: Sample Documentation Output
The next several pages show the output resulting from the processing of the
sample program shown in Appendix D. Date: 09-05-1992 Time: 19:47:14 Filename: D:\BASDOC\SAMPLE.BAS Subroutine: Main Page No: 1
1 DECLARE SUB EndProg ()
2 INPUT #1, I
3 ' Select case example
4 SELECT CASE I
5 CASE 1
6 1 PRINT "I="; I
7 CASE 2
8 2 PRINT "I="; -I
9 CASE 3
10 3 PRINT "I="; 0
11 END SELECT
12 'If example
13 IF I > 2 THEN
14 T PRINT "Yes"
15 ELSE
16 F PRINT "No"
17 END IF
18 'Do loop example
19 J = 1
20 DO UNTIL J = 5
21 L PRINT J
22 L J = J + 1
23 LOOP
24 'For example
25 FOR J = 1 TO 10
26 N PRINT -J
27 NEXT J
28 CALL EndProg
29 END
Local Variable Cross Reference for Subroutine: Main
EndProg 1 28
I 2 4 6 8 13
J 19 20 21 22 22 25 26 27
Local Keyword Cross Reference for Subroutine: Main
CALL 28
CASE 4 5 7 9
DECLARE 1
DO 20
ELSE 15
END 11 17 29
FOR 25
IF 13 17
INPUT 2
LOOP 23
NEXT 27
PRINT 6 8 10 14 16 21 26
SELECT 4 11
Date: 09-05-1992 Time: 19:47:14 Filename: D:\BASDOC\SAMPLE.BAS Subroutine: Main Page No: 2
SUB 1 31
THEN 13
TO 25
UNTIL 20
Date: 09-05-1992 Time: 19:47:14 Filename: D:\BASDOC\SAMPLE.BAS Subroutine: EndProg Page No: 3
1 SUB EndProg
2 J = 5 * 5
3 I = 5 ^ .33
4 PRINT "Five Squared is: "; J
5 PRINT "Cube root of twenty-five is: "; I
6 PRINT "End of Program"
7 END SUB
Local Variable Cross Reference for Subroutine: EndProg
EndProg 1
I 3 5
J 2 4
Local Keyword Cross Reference for Subroutine: EndProg
END 7
PRINT 4 5 6
SUB 7
Date: 09-05-1992 Time: 19:47:14 Filename: D:\BASDOC\SAMPLE.BAS Subroutine: Page No: 4
Date: 09-05-1992 Time: 19:47:14 Filename: D:\BASDOC\SAMPLE.BAS Subroutine: Page No: 5
Global Variable Cross Reference
EndProg Main EndProg
I Main EndProg
J Main EndProg
Date: 09-05-1992 Time: 19:47:14 Filename: D:\BASDOC\SAMPLE.BAS Subroutine: Page No: 6
Table of Contents
Subroutine File Page
Main D:\BASDOC\SAMPLE.BAS 1
EndProg D:\BASDOC\SAMPLE.BAS 3
Appendix F: Sample Indented Source File
DECLARE SUB EndProg ()
INPUT #1, I
' Select case example
SELECT CASE I
CASE 1
PRINT "I="; I
CASE 2
PRINT "I="; -I
CASE 3
PRINT "I="; 0
END SELECT
'If example
IF I > 2 THEN
PRINT "Yes"
ELSE
PRINT "No"
END IF
'Do loop example
J = 1
DO UNTIL J = 5
PRINT J
J = J + 1
LOOP
'For example
FOR J = 1 TO 10
PRINT -J
NEXT J
CALL EndProg
END
SUB EndProg
J = 5 * 5
I = 5 ^ .33
PRINT "Five Squared is: "; J
PRINT "Cube root of twenty-five is: "; I
PRINT "End of Program"
END SUB
